Backstage: el portal para desarrolladores de Spotify

Backstage, open-sourced por Spotify en 2020, es la base más usada para construir Internal Developer Platforms (IDPs). En 2023 se ha consolidado como referencia — adoptado por empresas como Spotify, American Airlines, Netflix, Roku y centenares más. No es un producto cerrado: es una plataforma extensible que cada organización adapta. Cubrimos cómo funciona, qué obtienes “out of the box”, y los costes de adopción que rara vez se mencionan en los talks.

Qué es realmente

Backstage es una aplicación web (Node.js + React) que actúa como portal único para todo lo que un desarrollador necesita en su trabajo:

• Catálogo de servicios: inventario centralizado de qué existe, quién lo mantiene, sus dependencias.
• Plugins: cada función adicional (CI/CD status, Kubernetes, monitoring, docs, costes cloud) viene como plugin enchufable.
• Scaffolder: generador de nuevos componentes a partir de plantillas.
• TechDocs: documentación como código, renderizada dentro del portal.
• Search: búsqueda federada sobre todo lo anterior.

La visión: un solo sitio donde el desarrollador encuentra qué existe, cómo crear cosas nuevas, dónde está la documentación, qué está pasando con sus servicios.

Software Catalog: el corazón

Cada cosa en Backstage es una entidad del catálogo, descrita por un YAML simple:

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: orders-api
  description: Servicio que gestiona órdenes de compra
spec:
  type: service
  lifecycle: production
  owner: team-orders
  system: ecommerce

Tipos de entidad principales: Component (servicios, librerías, websites), API, Resource (DBs, queues), System (agrupaciones), Group (equipos), User, Domain (áreas funcionales).

Las relaciones se infieren del YAML: “este componente pertenece al sistema X, su API es consumida por Y, está en el dominio Z”. Backstage construye una red navegable de toda la arquitectura.

El catálogo se alimenta de:

• Locations (URLs de YAMLs). Pueden vivir en el repo de cada servicio o centralizados.
• Providers que descubren entidades automáticamente (de un cluster de Kubernetes, GitHub orgs, etc.).
• Manualmente vía interfaz web.

Plugins: dónde está el ecosistema

Backstage solo es útil con plugins. Algunos esenciales:

• GitHub / GitLab: ver el repo, PRs, contributors directamente en el portal.
• CI/CD: status de builds, deploys, runs (Tekton, ArgoCD, Jenkins, GitHub Actions).
• Kubernetes: ver pods, deployments, eventos del componente actual.
• TechDocs: documentación markdown dentro del portal.
• PagerDuty / Opsgenie: oncall actual de cada servicio.
• Datadog / Grafana / NewRelic: dashboards embebidos del componente.
• Sentry / Rollbar: errores recientes.
• Cost Insights: coste cloud por servicio.

Hay 100+ plugins oficiales y community. Y construir el tuyo propio es un ejercicio de React + un par de archivos de configuración.

El Scaffolder: golden paths en acción

El scaffolder es donde Backstage convierte la promesa de “platform engineering” en reality. Defines templates que generan:

• Repositorio nuevo en GitHub con estructura estándar.
• Pipeline de CI configurado.
• Manifests de Kubernetes con resource limits y health checks.
• Dashboard de Grafana pre-creado.
• Alertas básicas.
• Entrada en el catálogo apuntando al nuevo componente.

Todo desde un wizard web donde el desarrollador rellena pocos campos (nombre, equipo, tipo). Lo que tomaría horas o días manualmente, se hace en un minuto.

Implementarlo requiere inversión: cada template es código (YAML + shell + actions de Backstage), y mantenerlo cuando las convenciones internas cambian es trabajo continuo.

TechDocs: docs como código

TechDocs renderiza markdown del repo del propio servicio dentro del portal. La idea: que la documentación viva con el código, se actualice en los mismos PRs, y se vea con buena UX en un sitio centralizado.

Internamente usa MkDocs como motor de renderizado. La integración es sencilla: añade un mkdocs.yml y carpeta docs/ al repo, refleja en el catalog-info.yaml, y aparece en Backstage.

Es una de las features más adoptadas porque resuelve un problema real: documentación dispersa entre confluence, wikis, READMEs y PDFs.

El coste real de adoptar Backstage

Los talks venden Backstage como “instalar y listo”. La realidad de implantarlo en serio:

• Equipo dedicado. Adoptarlo bien requiere 1-3 ingenieros full-time durante meses para configuración, plugins y migración.
• Inversión continua. Plugins evolucionan, integraciones cambian, templates necesitan mantenimiento. No es un “proyecto” — es un producto interno.
• Curva de aprendizaje React/Node.js. Si tu equipo es backend-heavy, adoptar el frontend de Backstage es nueva habilidad.
• Datos en buen estado. Si tu inventario actual es un Excel desfasado, Backstage no lo arreglará — solo lo expondrá.
• Adopción cultural. Los desarrolladores tienen que ir al portal, mantener su catalog-info, escribir TechDocs. Sin push organizativo, queda infrautilizado.

Para organizaciones con menos de 30-50 desarrolladores, la inversión rara vez compensa. Para organizaciones más grandes, el ROI puede ser sustancial — pero requiere compromiso real.

Alternativas y opciones gestionadas

Backstage no es la única opción:

• Port: SaaS managed con catálogo y portal, menor flexibilidad pero cero operación.
• Cortex: similar, foco en service catalog y scorecards.
• Roadie y Spotify Portal for Backstage: versión managed de Backstage por empresas externas.
• Construcción casera: para organizaciones con stack muy específico, a veces sale mejor un dashboard custom.

Conclusión

Backstage es la elección por defecto si tu organización tiene escala y compromiso para construir un IDP serio. Su flexibilidad es su fortaleza y su exigencia: te obliga a tomar decisiones que otras herramientas más opinionadas resuelven por ti. Si aciertas con la inversión y el respaldo organizativo, el resultado es valioso. Si lo abordas como “instalar Backstage los viernes”, quedará a medio camino.

Síguenos en jacar.es para más sobre platform engineering, IDP y experiencia de desarrollador.